Pascal Super Library/Pascal Super Library (CW International)(1997).bin/LIBRARY/SLTPU70C/MODEM.DOC

Text File | 1993-03-21 | 14KB | 316 lines

------------------------------------------------------------------------
Searchlight Modem Interface Unit              v3.0           March 1993
------------------------------------------------------------------------

Updates
Searchlight 3.0 adds several new functions to the modem driver unit. See
the end of this document for details.


Introduction

This unit provides functions which enable a Door program running under
Searchlight BBS (version 2.15C or later) to access Searchlight's serial port
drivers directly. While Searchlight supports Door programs indirectly via
the BIOS level output redirection, the functions provided here are important
if you wish to perform operations such as:

   ■ Output characters directly to the modem without displaying on the
     local screen
   ■ Output control characters or ANSI sequences directly to the modem
   ■ Control the modem input and output buffers
   ■ Perform your own carrier detection
   ■ Hang up on the remote user

The modem functions in this unit can be used in two ways. If your door
program is run with Searchlight BIOS modem redirection active (that is, in
"Standard" or "Force-Color" mode), you can perform the majority of your
input and output via standard read and write functions which access the
BIOS, supplementing these with function calls when a special feature such as
carrier detection, or hanging up the modem, is required. Alternately, if
your DOOR program runs with BIOS redirection disabled ("None" mode), you can
do all of your modem i/o directly through the function calls. For the vast
majority of programs, the first method is preferable, since it does not
require major changes to your source code.

Because these function calls use Searchlight's drivers directly, there is no
need to write modem control functions in your application and no need to do
any kind of direct hardware addressing. In addition, if Searchlight BBS is
configured to use a FOSSIL driver or a Digiboard, all of the function calls
in this unit will automatically be routed to the FOSSIL driver or Digiboard
driver in use. Thus, your program is assured of running correctly on any
properly configured Searchlight BBS installation, regardless of the serial
port configuration.

Note that although a Turbo Pascal source file is included, most functions
resolve to straight 8086 interrupt calls. This means that the functions are
readily translated to C or assembly language.

The Pascal unit also includes a data definition to the Searchlight "public"
data area and a public data area pointer; these features have been
documented previously, and will be briefly covered again here.



Functions, Variables & Type Definitions


Var DriverLoaded: boolean;             { Set if SLBBS drivers available }

This global variable is set automatically by the MODEM unit's initialization
code. It is set to TRUE if Searchlight modem drivers are available, FALSE
otherwise. A FALSE setting indicates that Searchlight is not loaded into
memory (ie. your program was not run as a door) or that the version of
Searchlight in memory is older than 2.15C. Modem control functions cannot be
used if this variable is FALSE.


Function CarrierDetect: boolean;       { Check carrier status }

This function checks the carrier detect signal on the modem. TRUE is
returned if carrier is detected, FALSE otherwise.


Procedure Hangup;                      { Disconnect (hangup) }

This procedure causes the modem to disconnect or hang up on the remote
caller. It's a good idea to call the WaitOut function before hanging up, to
assure that all pending output is sent.

Example:   WaitOut;
           Hangup;

Note: Your program should terminate IMMEDIATELY after calling Hangup, and
control MUST return directly to Searchlight BBS so that it may recycle
properly. Hangup should be used ONLY if your program executes directly from
Searchlight as an EXE file. Don't use this function if your program will run
from a batch file!


Function RS232Avail: boolean;         { Check RS232 char available }

This function returns TRUE if there is a character available to be read from
the modem input buffer.


Function RS232In: char;                { Read RS232 char }

This function reads a character from the modem input buffer. You should only
call RS232In if RS232Avail is TRUE.

Example:   If RS232Avail then c:=RS232In;   { c = char }


Procedure RS232Out (c: char);          { Write RS232 char }

Sends a character to the modem. You can send any ASCII character from 0 to
255. The character is sent directly to the modem without translation.

Example:   RS232Out(#27);   { Send clear screen sequence-- ESC[2J }
           RS232Out('[');
           RS232Out('2');
           RS232Out('J');


Procedure PauseOutput;                 { Pause buffered output }
Procedure RestartOutput;               { Restart output after pause }

If output buffering is active, these function calls allow you to pause and
restart the output to the modem. They have no effect if there is no output
buffering. Note: if a FOSSIL driver is used, these functions may or may not
work, depending on whether the FOSSIL driver implements them.


Procedure ClearInputBuffer;            { Clear input buffer }
Procedure ClearOutputBuffer;           { Clear output buffer }

These procedures clear the contents of the input buffer and output buffer,
respectively. Clearing the input buffer destroys any waiting input
characters; clearing the output buffer discards any characters which were
output but which have not yet been transmitted. As with PausOutput and
RestartOutput, the success of these functions when a FOSSIL driver is in use
will depend on the FOSSIL driver's implementation.


Function BufferEmpty: boolean;         { Check if output buffer empty }

This function returns TRUE if the output buffer is empty (or if there is no
output buffering). It returns FALSE if there are characters in the output
buffer. A FALSE result means that not all characters which were printed have
been transmitted to the remote terminal.


Procedure WaitOut;                     { Wait for output buffer to clear }

This procedure waits for the output buffer to clear, and returns when all
characters have been transmitted. It has no effect if the output buffer is
already empty or if no buffering is enabled. It is better to call this
function rather than test the BufferEmpty condition in a loop, since this
function is optimized for use in multitasking environments.

Example:   If (not Bufferempty) then WaitOut;


Var AUXIn: text;                       { RS232 Input File }
    AUXOut: text;                      { RS232 Output File }

These text file handlers can be used instead of the RS232In and RS232Out
procedures to provide input and output to the modem. Since they are text
files, you can use them in standard Pascal read and write statements.

Example:   Write(Auxout,#27'[2J');  { Send clear sequence. This has the same
                                      effect as the RS232Out example. }


Procedure ComToggle;                   { Toggle BIOS I/O support on and off }

This function toggles the BIOS redirection feature (ie. the function which
directs standard output and input through the modem) on and off. You should
only use this function if BIOS redirection is enabled when your program
begins (ie. if your program is run as a "Standard" or "Force-Color" type
door). ComToggle can be used whenever you wish to write text to the local
screen only.

Example:   Write('This message appears on both the local and remote screen.');
           ComToggle;
           Write('This message appears only on the local screen.');
           ComToggle;
           Write('This message again appears on both screens.');

You should also call ComToggle before executing any program that does its
own modem input and output-- for example, before calling a protocol engine
to perform an upload or download. Be sure that you toggle the com support
back on before your program exits.


type RSbaud = (B110,B150,B300,B600,B1200,B2400,B4800,B9600,B19200,B38400,
               b7200,b12000,b14400,b16800);
Procedure RSinit (com: integer; speed: RSbaud; buffactor: integer;
                  flow: boolean);

The RSInit function is available for users who wish to do all their I/O
directly through the procedures provided in this unit. You should only use
the RSInit, RSCleanup and SetPortAddress functions if your Door program has
been run in the "None" (no BIOS com support) mode from Searchlight. Do not
attempt to initialize the modem if BIOS I/O is active!

The following parameters are used with the RSInit function:

      Com:  Com port number (1-4)
    Speed:  Baud rate (from RSbaud type shown above)
Buffactor:  Output buffering factor (0-32)
     Flow:  Hardware flow control switch

You can find the proper values to use for these parameters by examining the
CONFIG.SL2 file.


Procedure RSCleanup;         { Reset RS232 port }

If you use RSInit to initialize the COM port, you should call RSCleanup to
de-initialize the port before your program exits.



Var  SLData: ^SLDataType;               { Pointer to public data area }

The Searchlight public data area is a block of memory inside the serial port
drivers which contains variables a Door program may be interested in
examining. The format of the data area is given by the SLDataType record
shown below. Variable 'SLData' is automatically initialized as a pointer to
this data area. (SLData is set to NIL if the public data area is not
available).

Example:   If SLData<>Nil then begin
             if SLData^.color then writeln('User has a color terminal.');
           end;


Type AnsiType = (GENERIC,PROCOMM,STANDARD);

     SLDataType = record         { Public Data Area }
      PROGID: string[6];                { Contains the string 'SLBBS' }
      carrier: boolean;                 { carrier check enabled? }
      writeprotect: boolean;            { disk write protection? }
      aborttype: byte;                  { 0=no abort, 1=terminate, 2=reboot }

      rsact: boolean;                   { set if rs232 active }
      ansi: boolean;                    { is user in ANSI mode? }
      color: boolean;                   { does user have a color crt? }
      directvid: boolean;               { system DirectVideo mode }

      curratt: byte;                    { current video attribute }
      commtype: byte;                   { run parameter - used internally }
      idletime: word;                   { idle limit (seconds) }
      lastkey: boolean;                 { TRUE = last key from local kbd }

      OldVector: array[$00..$7F] of pointer;   { old user int vectors }
      AnsiMode: AnsiType;               { user's ANSI mode }
     end;

Notes:
  The "carrier", "writeprotect" and "aborttype" flags reflect the status of
  carrier checking and write protection when the door was launched. Changing
  these flags has no effect.

  The "Rsact" flag is TRUE if the door was launched with BIOS I/O support
  (ie. "Standard" or "Force-Color" type door). It is set to FALSE if the
  door was launched in "None" mode (no modem support) OR if the door was
  run during a local login. (You can examine the CONFIG file to determine
  if the user is local or remote).

  You can still use the modem drivers if RSACT is false, but you must
  initialize the driver with RSInit.

  "DirectVid" tells you whether Searchlight is set to allow direct video
  writes in the CONFIG file.

  "LastKey" allows you to determine whether the last keystroke read from
  standard input originated from the modem or the local keyboard.

  "OldVector" stores the saved values of interrupts which Searchlight has
  intercepted. The ComToggle procedure uses these values.

  "AnsiMode" returns the ANSI terminal type selected by the user.

   Searchlight's active menu stack is also in this memory area. See the
   sample program "BackTrak" for more information.



The following New Functions are added as of Searchlight 3.0:

Function RSVersion: byte;             { Serial unit revision number }

This returns the version number of the serial driver unit that is available.
Searchlight 3.0 returns 2 as the version number. Previous versions will
return 0. You should check the version number before performing functions
which are only available in later revisions.



Procedure RS232StrOut (count,strseg,strofs: word);
  { write string to output }

This function writes an entire string of data to the serial port instead of
just a character. The maximum string length that may be output is 255. The
inputs correspond to the string length, and the segment and offset of the
first character in the string.

The proper way to call this function from Turbo Pascal, assuming "St" is
a string type variable, is:

   RS232StrOut(Length(St),Seg(St[1]),Ofs(St[1]));

Using RS232StrOut is more efficient than calling RS232Out multiple times,
since it eliminates multiple interrupt function calls. On standard COM ports
and FOSSIL drivers, Searchlight implements the RS232StrOut function by
calling the RS232Out function multiple times in a tight assembly language
loop. With Digiboards, Searchlight calls the Digiboard string output
function directly, eliminating loop overhead.


---------
FL'92/'93